Crate sled

sled is a high-performance embedded database with an API that is similar to a BTreeMap<[u8], [u8]>, but with several additional capabilities for assisting creators of stateful systems.

It is fully thread-safe, and all operations are atomic. Multiple Trees with isolated keyspaces are supported with the Db::open_tree method.

ACID transactions involving reads and writes to multiple items are supported with the Tree::transaction method. Transactions may also operate over multiple Trees (see Tree::transaction docs for more info).

Users may also subscribe to updates on individual Trees by using the Tree::watch_prefix method, which returns a blocking Iterator over updates to keys that begin with the provided prefix. You may supply an empty prefix to subscribe to everything.

Merge operators (aka read-modify-write operators) are supported. A merge operator is a function that specifies how new data can be merged into an existing value without requiring both a read and a write. Using the Tree::merge method, you may “push” data to a Tree value and have the provided merge operator combine it with the existing value, if there was one. They are set on a per-Tree basis, and essentially allow any sort of data structure to be built using merges as an atomic high-level operation.

sled is built by experienced database engineers who think users should spend less time tuning and working against high-friction APIs. Expect significant ergonomic and performance improvements over time. Most surprises are bugs, so please let us know if something is high friction.

Examples

let db: sled::Db = sled::open("my_db").unwrap();

// insert and get
db.insert(b"yo!", b"v1");
assert_eq!(&db.get(b"yo!").unwrap().unwrap(), b"v1");

// Atomic compare-and-swap.
db.compare_and_swap(
    b"yo!",      // key
    Some(b"v1"), // old value, None for not present
    Some(b"v2"), // new value, None for delete
)
.unwrap();

// Iterates over key-value pairs, starting at the given key.
let scan_key: &[u8] = b"a non-present key before yo!";
let mut iter = db.range(scan_key..);
assert_eq!(&iter.next().unwrap().unwrap().0, b"yo!");
assert_eq!(iter.next(), None);

db.remove(b"yo!");
assert_eq!(db.get(b"yo!"), Ok(None));

let other_tree: sled::Tree = db.open_tree(b"cool db facts").unwrap();
other_tree.insert(
    b"k1",
    &b"a Db acts like a Tree due to implementing Deref<Target = Tree>"[..]
).unwrap();

Re-exports

• pub use self::transaction::Transactional;

Modules

• doc
  what is sled?
• transaction
  Fully serializable (ACID) multi-Tree transactions

Structs

• Batch
  A batch of updates that will be applied atomically to the Tree.
• CompareAndSwapError
  Compare and swap error.
• Config
  Top-level configuration for the system.
• Db
  The sled embedded database! Implements Deref<Target = sled::Tree> to refer to a default keyspace / namespace / bucket.
• IVec
  A buffer that may either be inline or remote and protected by an Arc
• Iter
  An iterator over keys and values in a Tree.
• Subscriber
  A subscriber listening on a specified prefix
• Tree
  A flash-sympathetic persistent lock-free B+ tree.

Enums

• Error
  An Error type encapsulating various issues that may come up in the operation of a Db.
• Event
  An event that happened to a key that a subscriber is interested in.
• Mode
  The high-level database mode, according to the trade-offs of the RUM conjecture.

Traits

• MergeOperator
  A function that may be configured on a particular shared Tree that will be applied as a kind of read-modify-write operator to any values that are written using the Tree::merge method.

Functions

• open
  Opens a Db with a default configuration at the specified path. This will create a new storage directory at the specified path if it does not already exist. You can use the Db::was_recovered method to determine if your database was recovered from a previous instance. You can use Config::create_new if you want to increase the chances that the database will be freshly created.

Type Aliases

• Result
  The top-level result type for dealing with fallible operations. The errors tend to be fail-stop, and nested results are used in cases where the outer fail-stop error can have try ? used on it, exposing the inner operation that is expected to fail under normal operation. The philosophy behind this is detailed on the sled blog.